home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / libs / patchlib539.lha / patchlib / autodocs / patch.doc
Text File  |  1996-12-09  |  34KB  |  999 lines
  1. TABLE OF CONTENTS
  2.  
  3. patch.library/AddPatchNotifyA
  4. patch.library/CreatePatchProjectA
  5. patch.library/FindPatch
  6. patch.library/FindPatchTagsA
  7. patch.library/GetPatchA
  8. patch.library/InstallPatch
  9. patch.library/InstallPatchTagsA
  10. patch.library/PatchAlloc
  11. patch.library/PatchFreeVec
  12. patch.library/RemovePatch
  13. patch.library/RemovePatchProjectA
  14. patch.library/RemovePatchTagsA
  15. patch.library/RemPatchNotifyA
  16. patch.library/SetPatchA
  17. patch.library/SetPatchProjectA
  18. patch.library/WaitRemovePatch
  19.  
  20. patch.library/AddPatchNotifyA           patch.library/AddPatchNotifyA
  21.  
  22.    NAME
  23.     AddPatchNotifyA -- Get messages, if a patch is changed. (V5)
  24.     AddPatchNotify -- varargs stub for AddPatchNotifyA(). (V5)
  25.  
  26.    SYNOPSIS
  27.     Error = AddPatchNotifyA( msgport, taglist )
  28.     D0                     A0       A1
  29.  
  30.     ULONG Error AddPatchNotifyA( struct MsgPort *, struct TagItem *);
  31.  
  32.     Error = AddPatchNotify( msgport, firsttag, ...)
  33.  
  34.     ULONG Error AddPatchNotify( struct MsgPort *, Tag, ...);
  35.  
  36.    FUNCTION
  37.     Start sending out notification requests to the given messageport, if
  38.     a patch is added, removed or changed.
  39.  
  40.    INPUTS
  41.     msgport = pointer to msgport ready to receive messages or
  42.           null for no action
  43.     taglist = pointer to array of tags
  44.  
  45.    TAGS
  46.     PATT_Priority (BYTE) - Optional priority for the notification request
  47.         Normally only the priorities +5, 0, -5 should be used.
  48.  
  49.    RESULT
  50.     Error = errorcode as defined in patch.h.
  51.         PATERR_Ok
  52.             Indicates success of the operation.
  53.         PATERR_OutOfMem
  54.             Indicates that there was not enough memory to
  55.             complete the operation.
  56.  
  57.    NOTES
  58.  
  59.    BUGS
  60.  
  61.    SEE ALSO
  62.     RemPatchNotify(), patch.h
  63. patch.library/CreatePatchProjectA           patch.library/CreatePatchProjectA
  64.  
  65.    NAME
  66.     CreatePatchProjectA -- Create an instance of a patch project. (V4)
  67.     CreatePatchProject -- varargs stub for CreatePatchProjectA(). (V4)
  68.  
  69.    SYNOPSIS
  70.     project = CreatePatchProjectA( projectname, taglist )
  71.     D0                           A0           A1
  72.  
  73.     APTR CreatePatchProjectA( STRPTR, struct TagItem *);
  74.  
  75.     project = CreatePatchProject( projectname, firsttag, ...)
  76.  
  77.     APTR CreatePatchProject( STRPTR, Tag, ...);
  78.  
  79.    FUNCTION
  80.     Create an instance of a patch project.
  81.  
  82.     This instance may be used to manipulate or remove patches belonging
  83.     to one project (or program) with one function call.
  84.  
  85.     The projectname will be copied into an internal buffer.
  86.  
  87.    INPUTS
  88.     projectname = pointer to name of the patch project
  89.     taglist     = pointer to array of tags
  90.  
  91.    TAGS
  92.     none defined yet
  93.  
  94.    RESULT
  95.     project = pointer to patch projects private structure or 
  96.           null on failure
  97.  
  98.    NOTES
  99.  
  100.    BUGS
  101.  
  102.    SEE ALSO
  103.     RemovePatchProject(), InstallPatchTags(), patch.h
  104.   patch.library/FindPatch                               patch.library/FindPatch
  105.  
  106.    NAME
  107.     FindPatch -- find a patch structure with a given name.
  108.  
  109.    SYNOPSIS
  110.     patch = FindPatch( Name )
  111.     D0               A0
  112.  
  113.     struct Patch *FindPatch( STRPTR );
  114.  
  115.    FUNCTION
  116.     This function will search the patch.library lists for a
  117.     patch structure with the given name. The first patch matching
  118.     this name will be returned.
  119.  
  120.     This function exists only for historic reasons.
  121.     It will internally be routed to FindPatchTags().
  122.  
  123.    INPUTS
  124.     Name = Name of the patch structure to find
  125.  
  126.    RESULT
  127.     patch = a pointer to the patch structure with the same name else
  128.         zero to indicate that the string was not found.
  129.  
  130.    NOTES
  131.     If your task is not the owner of the patch, the
  132.     pointer is only valid as long as the system is in forbid().
  133.     From V2 on you may also lock the patch.library semaphore
  134.     before calling this function. In this case a pointer to
  135.     a patch structure is guaranteed to be valid, until you
  136.     release the semaphore. The semaphore, however, should be kept
  137.     locked only for short periods of time in order not to block
  138.     other tasks.
  139.  
  140.    BUGS
  141.  
  142.    SEE ALSO
  143.     InstallPatch(), RemovePatch(), Patch.h
  144.  patch.library/FindPatchTagsA                     patch.library/FindPatchTagsA
  145.  
  146.    NAME
  147.     FindPatchTagsA -- find a patch structure with certain criteria. (V3)
  148.     FindPatchTags -- varargs stub for FindPatchTagsA(). (V3)
  149.  
  150.    SYNOPSIS
  151.     object = FindPatchTagsA( taglist )
  152.     D0                 A0
  153.  
  154.     APTR FindPatchTagsA( struct TagItem *);
  155.  
  156.     object = FindPatchTags( firsttag, ...)
  157.  
  158.     APTR FindPatchTags( Tag, ...);
  159.  
  160.    FUNCTION
  161.     This function will search the patch.library lists for a
  162.     patch structure, that matches the criteria specified in the taglist.
  163.     The first matching patch will be returned.
  164.  
  165.    INPUTS
  166.     taglist = pointer to array of tags
  167.  
  168.    TAGS
  169.     Specify only one of these at a time:
  170.     PATT_PatchName (STRPTR) - Specifies that patch.library should
  171.         search for the occurrence of a patch of the given name.
  172.     PATT_ProjectName (V4) (STRPTR) - Specifies that patch.library should
  173.         search for the occurrence of a project of the given name.
  174.  
  175.  
  176.     PATT_NoCase (V4) (BOOL) - If specified with PATT_PatchName or
  177.         PATT_ProjectID string-comparison will be case-independent.
  178.         International characters are not respected with this version
  179.         of patch.library.
  180.         This may or may not change in the future.
  181.     PATT_LastObject (V4) (APTR) - This tag allows to search for multiple
  182.         matching objects. Simply specify the result of an previous
  183.         call to FindPatchTags() to continue searching with this tag.
  184.         You may also specify NULL to start searching the lists from
  185.         the beginning. Keep in mind, that you must make sure, that
  186.         the pointer is valid (see notes).
  187.  
  188.    RESULT
  189.     object = a pointer to the object as requested within the taglist or
  190.         zero to indicate that no match was found.
  191.  
  192.    NOTES
  193.     If your task is not the owner of the patch, the
  194.     pointer is only valid as long as the system is in forbid().
  195.     You may also lock the patch.library semaphore
  196.     before calling this function. In this case a pointer to
  197.     a patch structure is guaranteed to be valid, until you
  198.     release the semaphore. The semaphore, however, should be kept
  199.     locked only for short periods of time in order not to block
  200.     other tasks.
  201.  
  202.    BUGS
  203.  
  204.    SEE ALSO
  205.     InstallPatchTags(), RemovePatchTags(), PatchTags.h
  206.  patch.library/GetPatchA                               patch.library/GetPatchA
  207.  
  208.    NAME
  209.     GetPatchA -- Returns certain attributes of a patch. (V3)
  210.     GetPatch -- varargs stub for GetPatchA(). (V3)
  211.  
  212.    SYNOPSIS
  213.     Result = GetPatchA( patch, taglist )
  214.     D0                A0     A1
  215.  
  216.     ULONG Result GetPatchA( struct Patch *, struct TagItem *);
  217.  
  218.     Result = GetPatch( patch, firsttag, ...)
  219.  
  220.     ULONG Result GetPatch( struct Patch *, Tag, ...);
  221.  
  222.    FUNCTION
  223.     Returns certain attributes and lists connected to a patch (see TAGS).
  224.  
  225.    INPUTS
  226.     patch = pointer to a patch structure or NULL for no action
  227.     taglist = pointer to array of tags
  228.  
  229.    TAGS
  230.     PATT_Result2 (APTR) - An optional pointer to a longword, which will
  231.         contain an errorcode as defined patch.h, when
  232.         the function returns.
  233.         Assembler programmers can get the same value from d1.
  234.  
  235.     Only one of the following tags may be specified at a time:
  236.  
  237.     PATT_PatchName (BOOL) - Return a pointer to a copy of the name of
  238.         the patch in a null-terminated string.
  239.         This pointer must be passed to PatchFreeVec(), if
  240.         the string is no longer needed.
  241.         Type of Result is STRPTR.
  242.     PATT_TaskListType (BOOL) - Return the type of the internal TaskList
  243.         Possible results:
  244.         TL_TYPE_INCLUDE: all specified tasks will use the patchroutine,
  245.                  all others will ignore it.
  246.         TL_TYPE_EXCLUDE: all specified tasks will ignore the patchroutine,
  247.                  all others will use it.
  248.         NULL:         An error occurred (this includes the absence of
  249.                  a TaskList). Check the secondary errorcode for
  250.                  more information.
  251.         Type of Result is ULONG.
  252.     PATT_TaskList (BOOL) - Return a pointer to a taglist containing all
  253.         tasknames, taskids or patterns attached to a patch.
  254.         The tagitems are PATT_AddTaskName, PATT_AddTaskID or
  255.         PATT_AddTaskPattern(new for V5). Unknown tags must be ignored.
  256.         This pointer must be passed to PatchFreeVec(), if
  257.         the tasklist is no longer needed.
  258.         Type of Result is taglist.
  259.     PATT_Disabled (V4) (BOOL) - Return a number representing the current
  260.         disable nesting counter of a patch. Null means the patch is
  261.         enabled and will be used, by any tasks using the
  262.         library function.
  263.         Type of Result is ULONG.
  264.     PATT_UserData (V5) (BOOL) - Return userdata attached to a patch.
  265.         Type of Result is ULONG.
  266.     PATT_Priority (V5) (BOOL) - Return the priority of a patch.
  267.         Type of Result is BYTE.
  268.  
  269.  
  270.    RESULT
  271.     Result = Pointer or longword depending on specified tags.
  272.  
  273.     Possible errorcodes returned with PATT_Result2 or in register d1:
  274.         PATERR_Ok
  275.             Indicates success of the operation.
  276.         PATERR_OutOfMem
  277.             Indicates that there was not enough memory to
  278.             complete the operation.
  279.         PATERR_InvalidHandle
  280.             Indicates that the pointer to the patch passed
  281.             to the function was not or is no longer valid.
  282.             This might happen, if you pass a wrong pointer or
  283.             you got the pointer via FindPatch() and another
  284.             task has removed the patch before this task called
  285.             RemovePatchTags().
  286.         PATERR_NoTaskList
  287.             No valid TaskList is attached to the patch.
  288.             The SetPatchA() function with the PATT_CreateTaskList tag
  289.             specified, must be called to allocate a TaskList.
  290.         PATERR_PatchUnnamed
  291.             The patch has no identification string attached to it.
  292.  
  293.    NOTES
  294.  
  295.    BUGS
  296.  
  297.    SEE ALSO
  298.     InstallPatchTags(), PatchFreeVec(), Patch.h, PatchTags.h
  299.  patch.library/InstallPatch                         patch.library/InstallPatch
  300.  
  301.    NAME
  302.     InstallPatch -- Installs a patchroutine for library functions.
  303.  
  304.    SYNOPSIS
  305.     patch = InstallPatch( newPatch )
  306.     D0              A0
  307.  
  308.     struct Patch *InstallPatch( struct NewPatch * );
  309.  
  310.    FUNCTION
  311.     This function exists only for historic reasons. It will internally
  312.     routed back to InstallPatchTags(). Because InstallPatchTags()
  313.     has advanced features there is definitely no need to call this
  314.     function at all.
  315.  
  316.    INPUTS
  317.     NewPatch = pointer to an instance of a NewPatch structure
  318.  
  319.    RESULT
  320.     patch = pointer to a Patch structure or NULL on failure
  321.  
  322.    NOTES
  323.  
  324.    BUGS
  325.  
  326.    SEE ALSO
  327.     InstallPatchTags(), patchobsolete.h
  328.  patch.library/InstallPatchTagsA               patch.library/InstallPatchTagsA
  329.  
  330.    NAME
  331.     InstallPatchTagsA -- Installs a patchcode for library functions. (V2)
  332.     InstallPatchTags -- varargs stub for InstallPatchTagsA(). (V2)
  333.  
  334.    SYNOPSIS
  335.     patch = InstallPatchTagsA( funcEntry, funcOffset, tagList )
  336.     D0                    A0         D0          A1
  337.  
  338.     struct Patch *InstallPatchTagsA( APTR, UWORD, struct TagItem * );
  339.  
  340.     patch = InstallPatchTags( funcEntry, funcOffset, firsttag, ...)
  341.  
  342.     struct Patch *InstallPatchTags( APTR, UWORD, Tag, ...);
  343.  
  344.    FUNCTION
  345.     Adds a user provided routine to a library function.
  346.  
  347.     NEW for V3: An internal call to SetPatch() will be made.
  348.     So all tags which are valid with SetPatch() may be specified in the
  349.     taglist.
  350.  
  351.    INPUTS
  352.     funcEntry = pointer to the entry of the function to add
  353.     funcOffset = Library Offset Vector (LVO) of the function to patch
  354.     taglist = pointer to array of tags
  355.  
  356.    TAGS
  357.     PATT_LibraryName (STRPTR) - Specifies that you want to patch a library
  358.         of the given name ( as in exec.library/OpenLibrary() ).
  359.         Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase
  360.         MUST be specified.
  361.     PATT_DeviceName (STRPTR) - Specifies that you want to patch a device
  362.         of the given name ( as in exec.library/OpenDevice() ).
  363.         Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase
  364.         MUST be specified.
  365.     PATT_LibraryBase (struct Library *) Specifies that you want to patch
  366.         a library, device or resource with the given base.
  367.         You may get such a pointer by calling one of the following
  368.         exec functions: OpenLibrary(), OpenDevice(), OpenResource()
  369.         You may safely close this library, if InstallPatchTags()
  370.         returns, because patch.library will increase the OpenCount
  371.         to make sure, that the library won't be removed from the
  372.         system as long as there are patches installed.
  373.         V4: The OpenCount will not be increased, if the PatchSupervisor
  374.         support program is active.
  375.         Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase
  376.         MUST be specified.
  377.     PATT_LibVersion (ULONG) - Versionnumber for exec.library/OpenLibrary.
  378.         Optional in conjunction with PATT_LibraryName.
  379.         Should be specified, if a function is available only
  380.         from a certain library version on.
  381.         Default is NULL (any version).
  382.     PATT_DevFlags (ULONG) - Flags for exec.library/OpenDevice().
  383.         Optional in conjunction with PATT_DeviceName. Default is NULL.
  384.     PATT_DevUnit (ULONG) - Unit for exec.library/OpenDevice().
  385.         Optional in conjunction with PATT_DeviceName. Default is NULL.
  386.     PATT_PatchName (STRPTR) - An optional pointer to a string, which can
  387.         be used to search for a patch with FindPatch() or FindPatchTags().
  388.         The null-terminated string will be copied, so you may free
  389.         its memory when InstallPatchTags() returns. The string should
  390.         identify the program that installed the patch.
  391.         Even though this tag is optional, the use of it is strongly
  392.         encouraged, because without it certain future enhancements
  393.         of the patch.library may not work (e.g.: saving of user-settings).
  394.     PATT_Priority (BYTE) - Priority of the patch
  395.         valid range: -127...+126
  396.         It indicates the sequence of patches, if more than one patch
  397.         for a function is to be installed.
  398.         The original code has a priority of 0.
  399.         Priority:    Meaning:
  400.         >0: patch will be executed before the original
  401.         <0: patch will be executed after the original
  402.         =0: patch will be executed instead of the original (default)
  403.         Normally only the priorities +5, 0, -5 should be used.
  404.     PATT_NewCodeSize (ULONG) - Optional length of the patch code to be
  405.         installed.
  406.         If this field is set to the correct value the PC-RELATIVE
  407.         patch code starting at funcEntry will be copied into an
  408.         internal buffer. So it is possible to deallocate the
  409.         patch code after InstallPatchTags() returned.
  410.     PATT_Result2 (APTR) - An optional pointer to a longword, which will
  411.         contain an errorcode as defined patch.h, when
  412.         the function returns.
  413.         Assembler programmers can get the same value from d1.
  414.     PATT_ProjectID (APTR) (V4) - Optional pointer to a PatchProject as
  415.         created by a CreatePatchProject() function call, indicating
  416.         that the newly installed patch belongs to one project or program.
  417.         If used together with the RemovePatchProject() function
  418.         many patches can be removed with one function call.
  419.     PATT_UseXResult (BOOL) (V5) - If this tag is set to TRUE, your patchcode
  420.         MUST return a PatchXResult structure in d0.
  421.         See PatchAlloc for more informations.
  422.  
  423.  
  424.     For more tags see the description of SetPatch().
  425.  
  426.    RESULT
  427.     patch = pointer to a patch structure or NULL on failure
  428.  
  429.     Errorcodes returned with PATT_Result2, NPAT_Result2 or in register d1:
  430.     Note that from V3 on errorcodes may be returned, even if patch is a
  431.     valid pointer, indicating a failure in the internal SetPatch() call.
  432.     Previous versions always set PATERR_Ok, if patch was a valid pointer.
  433.         PATERR_Ok
  434.             Indicates success of the operation.
  435.         PATERR_OutOfMem
  436.             Indicates that there was not enough memory to
  437.             complete the operation.
  438.         PATERR_OpenLib
  439.             The operation failed, because the exec.library
  440.             function OpenLibrary() failed. Check the Autodocs
  441.             for more informations about OpenLibrary().
  442.         PATERR_OpenDev
  443.             The operation failed, because the exec.library
  444.             function OpenDevice() failed. Check the Autodocs
  445.             for more informations about OpenDevice().
  446.         PATERR_FuncNotStd
  447.             The library offset vector of the function to patch
  448.             was not in format that patch-library can accept.
  449.             Patch.library can handle the following formats:
  450.             jmp xxxxxx
  451.             moveq.l #xx,Dx    bra.l xxxx
  452.             moveq.l #xx,Dx    bra.s xx
  453.             Note that this is the type of error returned,
  454.             if you are trying to patch a function that uses
  455.             in-line code such as the exec.library/GetCC() function.
  456.         PATERR_InvalidTags
  457.             An error occurred while parsing the specified Tags
  458.             (e.g.: EITHER PATT_LibraryName, PATT_DeviceName or
  459.             PATT_LibraryBase MUST be used with InstallPatchTags() )
  460.     For more errorcodes see the description of SetPatch().
  461.  
  462.    NOTES
  463.     This function may implicitly call dos.library functions, so do not
  464.     call it from tasks.
  465.  
  466.    BUGS
  467.     Up to V4 it was not possible to pass pathnames with PATT_LibraryName or
  468.     PATT_DeviceName (e.g.: "Work:libs/foo.library"). This has been fixed
  469.     in V5.
  470.  
  471.    SEE ALSO
  472.     RemovePatchTags(), RemovePatchProject(), SetPatch(), PatchAlloc(),
  473.     Patch.h, PatchTags.h, exec.library/OpenLibrary(),
  474.     exec.library/OpenDevice()
  475.  patch.library/PatchAlloc                               patch.library/PatchAlloc
  476.  
  477.    NAME
  478.     PatchAlloc -- Allocate and initialize structures (V5)
  479.  
  480.    SYNOPSIS
  481.     structure = PatchAlloc(type)
  482.                        D0
  483.  
  484.     void *PatchAlloc(ULONG type);
  485.  
  486.    FUNCTION
  487.     Allocate and initialize structures for use with patch.library.
  488.  
  489.    NOTE
  490.     Call PatchFreeVec() to free the memory unless documented otherwise.
  491.  
  492.    INPUTS
  493.     type = type of structure to allocate
  494.  
  495.     Currently defined types:
  496.     PS_TYPE_XRESULT - Allocate a PatchXResult structure used 
  497.                           in conjunction with the Extended-Result-System
  498.               (See Example below)
  499.  
  500.    RESULT
  501.     structure = pointer to a structure or NULL on failure
  502.  
  503.    EXAMPLE
  504.     To add 30 ticks to the each dos.library/Delay() function
  505.     your patchcode would look like this (in SAS/C):
  506.  
  507.     __asm __saveds struct PatchXResult *MyDelay(register __d1 ULONG ticks)
  508.     {
  509.         struct PatchXResult *xresult;
  510.         ticks += 30;
  511.         if (xresult = (struct PatchXResult *)PatchAlloc(PS_TYPE_XRESULT))
  512.         {
  513.             xresult->pxr_RegD1 = ticks;
  514.             xresult->pxr_RegPattern = PATREG_D1;
  515.         }
  516.         return(xresult);
  517.     }
  518.  
  519.  
  520.    SEE ALSO
  521.     GetPatch(), exec.library/FreeVec
  522.  patch.library/PatchFreeVec                         patch.library/PatchFreeVec
  523.  
  524.    NAME
  525.     PatchFreeVec -- free memory allocated by GetPatch() (V3)
  526.  
  527.    SYNOPSIS
  528.     PatchFreeVec(memoryBlock)
  529.              A1
  530.  
  531.     void PatchFreeVec(void *);
  532.  
  533.    FUNCTION
  534.     Free a memory allocation made by the GetPatch() call. The memory will
  535.     be returned to the system pool from which it came.
  536.  
  537.    NOTE
  538.  
  539.    INPUTS
  540.     memoryBlock - pointer to the memory block to free, or NULL.
  541.  
  542.    SEE ALSO
  543.     GetPatch(), exec.library/FreeVec
  544.  patch.library/RemovePatch                           patch.library/RemovePatch
  545.  
  546.    NAME
  547.     RemovePatch -- Removes a patch installed by InstallPatch().
  548.  
  549.    SYNOPSIS
  550.     Error = RemovePatch( patch )
  551.     D0                 A0
  552.  
  553.     ULONG Error RemovePatch( struct Patch * );
  554.  
  555.    FUNCTION
  556.     This function is obsolete from V2 on, use RemovePatchTags() instead.
  557.     It effectively calls the new function
  558.     RemovePatchTags(patch, PATT_DelayedExpunge, FALSE, TAG_DONE)
  559.  
  560.    INPUTS
  561.     patch = pointer to the patch structure or NULL for no action
  562.  
  563.    RESULT
  564.     Error = errorcode as defined in patch.h.
  565.         (for more information see RemovePatchTags() )
  566.  
  567.    NOTES
  568.  
  569.    BUGS
  570.  
  571.    SEE ALSO
  572.     RemovePatchTags(), Patch.h
  573.  patch.library/RemovePatchProjectA           patch.library/RemovePatchProjectA
  574.  
  575.    NAME
  576.     RemovePatchProjectA -- Remove all patches from the same project. (V4)
  577.     RemovePatchProject -- varargs stub for RemovePatchProjectA(). (V4)
  578.  
  579.    SYNOPSIS
  580.     Error = RemovePatchProjectA( project, taglist )
  581.     D0                         A0       A1
  582.  
  583.     ULONG Error RemovePatchProjectA( APTR, struct TagItem *);
  584.  
  585.     Error = RemovePatchProject( project, firsttag, ...)
  586.  
  587.     ULONG Error RemovePatchProject( APTR, Tag, ...);
  588.  
  589.    FUNCTION
  590.     Remove all patches from the given project.
  591.  
  592.     This function simplifies the way, patches can be removed:
  593.     - All patches belonging to one project will be disabled
  594.     - The function then waits (depending on PATT_Timeout) until
  595.       the usagecounter of all patches becomes zero
  596.     - Now all patches will be removed via RemovePatchTags()
  597.     - If all patches are removed resources connected to the
  598.       project will be deallocted
  599.  
  600.     You may call this function to cleanup a project, even if no
  601.     patch was successfully installed for this project.
  602.  
  603.    INPUTS
  604.     project = pointer to a patch project obtained via CreatePatchProject()
  605.     taglist = pointer to array of tags
  606.  
  607.    TAGS
  608.     same as RemovePatchTags()
  609.  
  610.    RESULT
  611.     Error = errorcode as defined in patch.h.
  612.         same as RemovePatchTags()
  613.  
  614.    NOTES
  615.     Removing a patch routine can never be made absolutely safe.
  616.     Although patch.library does anything possible to provide methods
  617.     to minimize the chance of a crash, there will always be a
  618.     slight chance.
  619.     So minimize the number of install and remove operations.
  620.  
  621.    BUGS
  622.  
  623.    SEE ALSO
  624.     CreatePatchProject(), InstallPatchTags(), RemovePatchTags(),
  625.     Patch.h, PatchTags.h
  626.  patch.library/RemovePatchTagsA                 patch.library/RemovePatchTagsA
  627.  
  628.    NAME
  629.     RemovePatchTagsA -- Removes an installed patch. (V2)
  630.     RemovePatchTags -- varargs stub for RemovePatchTagsA(). (V2)
  631.  
  632.    SYNOPSIS
  633.     Error = RemovePatchTagsA( patch, taglist )
  634.     D0                      A0     A1
  635.  
  636.     ULONG Error RemovePatchTagsA( struct Patch *, struct TagItem *);
  637.  
  638.     Error = RemovePatchTags( patch, firsttag, ...)
  639.  
  640.     ULONG Error RemovePatchTags( struct Patch *, Tag, ...);
  641.  
  642.    FUNCTION
  643.     Removes a patch from a library function.
  644.  
  645.     All allocated resources for that specific patch will
  646.     be deallocated.
  647.  
  648.    INPUTS
  649.     patch = pointer to a patch structure or NULL for no action
  650.     taglist = pointer to array of tags
  651.  
  652.    TAGS
  653.     PATT_TimeOut (ULONG) - The number of ticks (1/50 seconds) the
  654.         function keeps trying to remove the patch, if another task
  655.         is running in the patchcode.
  656.         If the patch.library does not succeed in the given time the
  657.         function will return PATERR_PatchInUse.
  658.         Defaults to NULL, which means no retry.
  659.     PATT_DelayedExpunge (BOOL) - If this tag is not set to FALSE and a
  660.         non-patch.library patch was installed after the patch.library
  661.         patch for a specific library function the specified patch
  662.         will nevertheless be removed.
  663.         BUT some resources will be kept allocated by patch.library
  664.         (e.g.: the Library Offset Vector will not be restored to its
  665.         old state). Patch.library will try to deallocate these
  666.         resources automatically, if the system is getting low on
  667.         memory or if a call to a patch.library function that
  668.         removes or installs patches is made.
  669.         The default is TRUE !!!
  670.  
  671.    RESULT
  672.     Error = errorcode as defined in patch.h.
  673.         PATERR_Ok
  674.             Indicates success of the operation.
  675.         PATERR_PatchInUse
  676.             Indicates that some other task is using the
  677.             installed function and the patch can't be removed now.
  678.             Your task may wait and try again later.
  679.         PATERR_PatchInstalled
  680.             Indicates that a patchcode has been installed for
  681.             that function after your patch.library patch has
  682.             been installed and your patch is the only
  683.             patch.library patch for that function.
  684.             If patch.library would remove your patch
  685.             tasks would jump into deallocated memory
  686.             Result:  blinking borders.
  687.             Never occurs, if you pass in the tag
  688.             PATT_DelayedExpunge with TRUE.
  689.         PATERR_InvalidHandle
  690.             Indicates that the pointer to the patch passed
  691.             to the function was not or is no longer valid.
  692.             This might happen, if you pass a wrong pointer or
  693.             you got the pointer via FindPatch() and another
  694.             task has removed the patch before this task called
  695.             RemovePatchTags().
  696.             Also keep in mind that ln_Type must be PS_TYPE_USER.
  697.  
  698.    NOTES
  699.     Removing a patch routine can never be made absolutely safe.
  700.     Although patch.library does anything possible to provide methods
  701.     to minimize the chance of a crash, there will always be a
  702.     slight chance.
  703.     So minimize the number of install and remove operations.
  704.  
  705.     This function may implicitly call dos.library functions, so do not
  706.     call it from tasks.
  707.  
  708.    BUGS
  709.  
  710.    SEE ALSO
  711.     InstallPatchTags(), RemovePatchProject(), Patch.h, PatchTags.h
  712. patch.library/RemPatchNotifyA           patch.library/RemPatchNotifyA
  713.  
  714.    NAME
  715.     RemPatchNotifyA -- Stop receiving messages, if a patch is changed. (V5)
  716.     RemPatchNotify -- varargs stub for RemPatchNotifyA(). (V5)
  717.  
  718.    SYNOPSIS
  719.     Error = RemPatchNotifyA( msgport, taglist )
  720.     D0                     A0       A1
  721.  
  722.     ULONG Error RemPatchNotifyA( struct MsgPort *, struct TagItem *);
  723.  
  724.     Error = RemPatchNotify( msgport, firsttag, ...)
  725.  
  726.     ULONG Error RemPatchNotify( struct MsgPort *, Tag, ...);
  727.  
  728.    FUNCTION
  729.     Stop recieving notification requests for the given messageport.
  730.     The messageport should have been used in a previous call to
  731.     AddPatchNotify(). Before deallocating your MsgPort you must
  732.     still reply outstanding messages.
  733.  
  734.    INPUTS
  735.     msgport = pointer to msgport or null for no action
  736.     taglist = pointer to array of tags
  737.  
  738.    TAGS
  739.     none defined yet
  740.  
  741.    RESULT
  742.     Error = errorcode as defined in patch.h.
  743.         PATERR_Ok
  744.             Indicates success of the operation.
  745.  
  746.    NOTES
  747.  
  748.    BUGS
  749.  
  750.    SEE ALSO
  751.     AddPatchNotify(), patch.h
  752.  patch.library/SetPatchA                               patch.library/SetPatchA
  753.  
  754.    NAME
  755.     SetPatchA -- Changes certain attributes of a patch. (V3)
  756.     SetPatch -- varargs stub for SetPatchA(). (V3)
  757.  
  758.    SYNOPSIS
  759.     Error = SetPatchA( patch, taglist )
  760.     D0               A0     A1
  761.  
  762.     ULONG Error SetPatchA( struct Patch *, struct TagItem *);
  763.  
  764.     Error = SetPatch( patch, firsttag, ...)
  765.  
  766.     ULONG Error SetPatch( struct Patch *, Tag, ...);
  767.  
  768.    FUNCTION
  769.     Changes certain attributes of a patch (see TAGS).
  770.  
  771.    INPUTS
  772.     patch = pointer to a patch structure or NULL for no action
  773.     taglist = pointer to array of tags
  774.  
  775.    TAGS
  776.     PATT_CreateTaskList (ULONG) - Create a TaskList of the given type:
  777.         TL_TYPE_INCLUDE: all specified tasks will use the patchroutine,
  778.                  all others will ignore it.
  779.                  So if no Task is specified via PATT_AddTask... tags,
  780.                  the patchroutine will be used for NO tasks!
  781.         TL_TYPE_EXCLUDE: all specified tasks will ignore the patchroutine,
  782.                  all others will use it.
  783.                  So if no Task is specified via PATT_AddTask... tags,
  784.                  the patchroutine will be used for ALL tasks!
  785.     PATT_DeleteTaskList (BOOL) - Delete any existing TaskList
  786.         This will return the patch to its default behaviour, which is to call
  787.         the patchroutine for any task.
  788.         It is not required to remove the TaskList, before you remove a patch,
  789.         (via RemovePatchTags()) because this will automatically be done
  790.         by patch.library.
  791.     PATT_AddTaskID (struct Task *) - Add a task address to the patch TaskList.
  792.         Patch.library takes care that one TaskID appears only once in the
  793.         TaskList.
  794.         Unlike many tags, you may specify this tag more than once in one
  795.         taglist to add multiple tasks to the list.
  796.     PATT_AddTaskName (STRPTR) - Add a task of the given name to address to 
  797.         the patch TaskList. The string will be copied into an
  798.         internal buffer.
  799.         Patch.library takes care that one TaskName appears only once in the
  800.         TaskList.
  801.         Unlike many tags, you may specify this tag more than once in one
  802.         taglist to add multiple tasks to the list.
  803.     PATT_RemTaskID (struct Task *) - Remove a task address from the TaskList
  804.         Unlike many tags, you may specify this tag more than once in one
  805.         taglist to remove multiple tasks from the list.
  806.     PATT_RemTaskName (APTR) - Remove a task of the given name from the
  807.         TaskList.
  808.         Unlike many tags, you may specify this tag more than once in one
  809.         taglist to remove multiple tasks from the list.
  810.     PATT_Disabled (V4) (BOOL) - Enable (False) or disable (True) a patch.
  811.         For disabling a patch a nesting counter is provided.
  812.         In order to restore normal patch execution, the programmer must
  813.         provide exactly one call to 'enable' for every 'disable'.
  814.         If a patch is disabled this does not mean, that no task continues to
  815.         use the patched code. It only makes sure, that no further tasks enter
  816.         the patch code.
  817.         If PATT_Disabled,TRUE is set with InstallPatchTags() the patch will
  818.         not be called until explicitly enabled by a call to SetPatchTags().
  819.     PATT_AddRemoveHook (V4) (struct Hook *) - Add a Hook, which is called by
  820.         patch.library whenever a patch is removed from memory. Neither
  821.         the Hook structure nor the hookfunction are copied into internal
  822.         memory. So freeing these structures must be accomplished by the
  823.         hookfunction itself. It must also preserve all registers.
  824.         The hookobject (Register A2) for this hook is the patch structure.
  825.         For more information about hooks see utility/hooks.h,
  826.         utility.library/CallHook() or the RKMs.
  827.         Unlike many tags, you may specify this tag more than once in one
  828.         taglist to add multiple hooks.
  829.     PATT_RemRemoveHook (V4)    (struct Hook *) - Remove a Hook installed 
  830.         with PATT_AddRemoveHook.
  831.         Unlike many tags, you may specify this tag more than once in one
  832.         taglist to remove multiple hooks.
  833.     PATT_UserData (V5) (ULONG) - Attach userdata to a patch.
  834.         Use this tag only, if you are the owner (creator) of the patch.
  835.     PATT_AddTaskPattern (V5) (STRPTR) - Add a pattern of tasknames to the patch
  836.         TaskList. The pattern may contain dos wildcards.
  837.         Patch.library takes care that one pattern appears only once in the
  838.         TaskList.
  839.         Unlike many tags, you may specify this tag more than once in one
  840.         taglist to add multiple patterns to the list.
  841.         This tag only works with kickstart V37+.
  842.         DO NOT USE this tag, if you patch one of the following dos-functions:
  843.         MatchPattern() or MatchPatternNocase()
  844.     PATT_RemTaskPattern (V5) (STRPTR) - Remove a taskpattern from the
  845.         TaskList.
  846.         Unlike many tags, you may specify this tag more than once in one
  847.         taglist to remove multiple patterns from the list.
  848.     PATT_StackSize (V5) (ULONG) - Minimum stacksize (in bytes) your function
  849.         requires. This value should be a multiple of 4 and more than 256.
  850.         If a taskpattern (see PATT_AddtaskPattern) is active,
  851.         at least 1500 Bytes should be specified.
  852.         DO NOT USE this tag, if you patch one of the following exec-functions:
  853.         FindTask(), AllocMem(), FreeMem() or StackSwap()
  854.         You may specify zero to turn stack extension off.
  855.     PATT_Priority (V5) (BYTE) - Priority of the patch
  856.         valid range: -127...+126
  857.         It indicates the sequence of patches, if more than one patch
  858.         for a function is to be installed.
  859.         The original code has a priority of 0.
  860.         Priority:    Meaning:
  861.         >0: patch will be executed before the original
  862.         <0: patch will be executed after the original
  863.         =0: patch will be executed instead of the original (default)
  864.         Normally only the priorities +5, 0, -5 should be used.
  865.         Changing the priority of an active patch is a difficult
  866.         operation. It may fail with PATERR_PatchInUse.
  867.         You MUST NOT change the priority of a patch in respect
  868.         to the original function (see above).
  869.  
  870.  
  871.  
  872.    RESULT
  873.     Error = errorcode as defined in patch.h.
  874.         PATERR_Ok
  875.             Indicates success of the operation.
  876.         PATERR_OutOfMem
  877.             Indicates that there was not enough memory to
  878.             complete the operation.
  879.         PATERR_PatchInUse
  880.             Indicates that some other task is using the
  881.             installed function and the priority of the patch can't
  882.             be changed right now.
  883.             Your task may wait and try again later.
  884.         PATERR_InvalidHandle
  885.             Indicates that the pointer to the patch passed
  886.             to the function was not or is no longer valid.
  887.             This might happen, if you pass a wrong pointer or
  888.             you got the pointer via FindPatch() and another
  889.             task has removed the patch before this task called
  890.             RemovePatchTags().
  891.         PATERR_NoTaskList
  892.             No valid TaskList is attached to the patch.
  893.             The SetPatchA() function with the PATT_CreateTaskList tag
  894.             specified, must be called to allocate a TaskList.
  895.         PATERR_TaskListExists
  896.             PATT_CreateTaskList was specified, but there already
  897.             exists a TaskList.
  898.         PATERR_InvalidTaskList
  899.             PATT_CreateTaskList was specified with a wrong parameter
  900.         PATERR_KickTooOld
  901.             PATT_AddTaskPattern was used on a system with Kickstart V36
  902.             or lower.
  903.         PATERR_InvalidPattern
  904.             PATT_AddTaskList was used with a string, which contained an
  905.             invalid pattern. See dos.library ParsePattern() for more
  906.             informations.
  907.         PATERR_Restricted
  908.             PATT_AddTaskPattern or PATT_StackSize was used for a
  909.             forbidden function (see TAGS).
  910.  
  911.    NOTES
  912.     Using the TaskList feature provided by this function will
  913.     (by a huge amount in the case of PATT_AddTaskPattern) increase
  914.     the stackusage of the patched function.
  915.     See PATT_StackSize for a solution.
  916.  
  917.    BUGS
  918.  
  919.    SEE ALSO
  920.     InstallPatchTags(), Patch.h, PatchTags.h, dos.library/ParsePatternNoCase(),
  921.     dos.library/ParsePattern()
  922.  patch.library/SetPatchProjectA                 patch.library/SetPatchProjectA
  923.  
  924.    NAME
  925.     SetPatchProjectA -- Changes certain attributes of a project. (V5)
  926.     SetPatchProject -- varargs stub for SetPatchProjectA(). (V5)
  927.  
  928.    SYNOPSIS
  929.     Error = SetPatchProjectA( project, taglist )
  930.     D0                      A0       A1
  931.  
  932.     ULONG Error SetPatchProjectA( project, struct TagItem *);
  933.  
  934.     Error = SetPatchProject( project, firsttag, ...)
  935.  
  936.     ULONG Error SetPatchProject( project, Tag, ...);
  937.  
  938.    FUNCTION
  939.     Changes certain attributes of a group of patches belonging to one
  940.     project. For now (V5) it mainly calls SetPatch() recursively for
  941.     all patches belonging to the project.
  942.     Certain project specific tags may be implemented later.
  943.  
  944.    INPUTS
  945.     project = pointer to a patch project obtained via CreatePatchProject()
  946.               or NULL for no action
  947.     taglist = pointer to array of tags
  948.  
  949.    TAGS
  950.     see SetPatch() for a list of valid tags.
  951.  
  952.    RESULT
  953.     Error = errorcode as defined in patch.h.
  954.         see SetPatch() for a list of errorcodes
  955.  
  956.    NOTES
  957.     Currently (V5) SetPatchProject() stops changing patches, when any of
  958.     the internal calls to SetPatch() return an error. Therefore when
  959.     SetPatchProject() returns an error, some patches may have been changed
  960.     and others not.
  961.  
  962.    BUGS
  963.  
  964.    SEE ALSO
  965.     SetPatch(), Patch.h, PatchTags.h, 
  966.  patch.library/WaitRemovePatch                   patch.library/WaitRemovePatch
  967.  
  968.    NAME
  969.     WaitRemovePatch -- Waits until it is possible to remove a patch.
  970.  
  971.    SYNOPSIS
  972.     Error = WaitRemovePatch( patch )
  973.     D0                 A0
  974.  
  975.     ULONG Error WaitRemovePatch( struct Patch * );
  976.  
  977.    FUNCTION
  978.     This function is obsolete from V2 on, use RemovePatchTags() instead.
  979.     It effectively calls the new function
  980.     RemovePatchTags(patch,  PATT_TimeOut, 0x7fffffff,
  981.                 PATT_DelayedExpunge, FALSE,
  982.                 TAG_DONE)
  983.  
  984.    INPUTS
  985.     patch = pointer to the patch structure or NULL for no action
  986.  
  987.    RESULT
  988.     Error = errorcode as defined in patch.h.
  989.         (for more information see RemovePatchTags() )
  990.  
  991.    NOTES
  992.  
  993.    BUGS (?)
  994.     This function will never return, if the patched library function
  995.     crashed for some reason.
  996.  
  997.    SEE ALSO
  998.     RemovePatchTags()
  999.